consciousness

@one710/意识

](https://www.npmjs.com/package/@one710/consciousness) ](https://www.npmjs.com/package/@one710/consciousness)  

一个功能强大、可插拔的向量内存和模型上下文协议（MCP）服务器，用于本地语义搜索和长期内存。

特性

• MCP集成：与模型上下文协议完全兼容。
• 会话范围和通用内存：作用域工具按以下方式隔离内存 sessionId通用工具提供共享的、独立于会话的存储。
• 可插拔架构：轻松交换嵌入提供程序和矢量存储。
• 多个存储后端：通过可选入口点访问内存、文件系统、ChromaDB和Supabase（pgvector）。
• 可选嵌入入口点：Hugging Face和AI SDK提供商仅在从导入时加载 @one710/consciousness/huggingface 或 @one710/consciousness/aisdk.
• 语义搜索：使用最先进的嵌入技术进行智能内存检索。
• DTS索引：使用样本距离（DTS）逻辑优化搜索。

快速入门（使用npx）

您可以直接运行意识MCP服务器，无需安装 npx:

npx @one710/consciousness

默认情况下，这将使用 FilesystemVectorStore （坚持到 ./memory_store.json)以及 HFEmbeddingProvider.

安装

npm install @one710/consciousness

代码中的用法

创建MCP服务器

import { createServer, MemoryVectorStore } from "@one710/consciousness";
import { HFEmbeddingProvider } from "@one710/consciousness/huggingface";

const provider = new HFEmbeddingProvider();
const store = new MemoryVectorStore(provider);
const server = createServer("my-server", "1.0.0", store);

// Connect to transport (e.g., Stdio)
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const transport = new StdioServerTransport();
await server.connect(transport);

嵌入提供商

拥抱的脸（当地）

用途 @huggingface/transformers 在CPU/GPU上本地生成嵌入。导入可选条目，以便在使用此提供程序之前，主包图不会加载Transformers：

import { HFEmbeddingProvider } from "@one710/consciousness/huggingface";

const provider = new HFEmbeddingProvider();

AI SDK（云/远程）

使用Vercel AI SDK连接到任何受支持的提供商（例如OpenAI、Anthropic、Google）。安装 ai 以及您使用的提供程序包，然后导入：

import { AISDKEmbeddingProvider } from "@one710/consciousness/aisdk";
import { openai } from "@ai-sdk/openai";

const provider = new AISDKEmbeddingProvider(
  openai.embedding("text-embedding-3-small"),
  1536, // Dimensions
);

向量存储

内存存储（内存中）

import { MemoryVectorStore } from "@one710/consciousness";

const store = new MemoryVectorStore(provider);

文件系统存储（本地持久性）

import { FilesystemVectorStore } from "@one710/consciousness";

const store = new FilesystemVectorStore(provider, "./memory-data.json");

Chroma商店（分布式/管理式）

安装 chromadb 在这个包旁边，然后导入可选条目（主包不依赖于Chroma）：

import { ChromaVectorStore } from "@one710/consciousness/chroma";
import { ChromaClient } from "chromadb";

const client = new ChromaClient();
const store = new ChromaVectorStore(provider, client, "my-collection");

Supabase商店（pgvector）

安装 @supabase/supabase-js，在下应用SQL supabase/migrations/ 在你的项目中。在这次迁移中，set embedding_dim 在 DO 根据提供商的宽度（例如。 1536 OpenAI text-embedding-3-small, 384 对于默认的MiniLM模型）。然后：

import { createClient } from "@supabase/supabase-js";
import { SupabaseVectorStore } from "@one710/consciousness/supabase";

const client = createClient(url, key);
const store = new SupabaseVectorStore(provider, client);

与Sessions合作

所有店铺运营都需要 sessionId 隔离记忆：

const sessionId = "user-123";

// Store a memory
await store.add(sessionId, "The capital of France is Paris");

// Search within the session
const results = await store.search(sessionId, "France", {
  method: "cosine",
  limit: 5,
});

// Forget a specific memory
await store.forget(sessionId, results[0].item.id);

// Clear all memories for the session
await store.clear(sessionId);

MCP工具

MCP服务器公开了两组工具：

范围内的工具（需要 sessionId)

通用工具（无 sessionId 需要）

本地Supabase（Docker）和测试

该仓库包括一个Supabase CLI项目 supabase/.与 码头工人 正在运行：

yarn supabase:start

这会拉取图像，应用 supabase/migrations/，并在中公开API http://127.0.0.1:54321 （参见 yarn supabase:status).停止 yarn supabase:stop.

集成测试 test/supabase-vector-store.test.ts 使用默认本地URL探测该URL 服务角色 JWT。如果堆栈已关闭，它们将跳过并发出简短的控制台警告，因此 yarn test 仍然完成。要强制跳过它们（例如在没有Docker的CI中）：

SKIP_SUPABASE_TESTS=1 yarn test

要仅运行Supabase测试，请执行以下操作：

yarn supabase:start   # once per machine session
yarn test:supabase

需要时覆盖URL/键： SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY （或 API_URL / SERVICE_ROLE_KEY 从 supabase status --output env).

通过Docker Compose实现Chroma+Supabase（集成测试）

跑 色度 （港口 8000), Postgres+pgvector （主持人 54332), PostgREST，还有一个小 引擎X 网关如此 @supabase/supabase-js 继续使用 /rest/v1/ 它所期望的路径。默认设置可避免在上与Supabase CLI冲突 54321 / 54322；用于测试的API为 http://127.0.0.1:54331.

yarn docker:test:up    # wait until containers are healthy
yarn docker:test       # sets SUPABASE_URL=http://127.0.0.1:54331 and runs the full suite
yarn docker:test:down  # stop and remove volumes

yarn test 预期 本地主机上的色度：8000 （例如。 yarn docker:test:up 在完整运行之前）。 test/chroma.test.ts 用途 ChromaClient 默认设置为与组合映射匹配。 SKIP_SUPABASE_TESTS 仍然适用于上无法访问与Subabase-兼容的API的情况 SUPABASE_URL （默认值 http://127.0.0.1:54321).

许可证

该项目根据 MIT许可证.