@one710/consciousness

A powerful, pluggable vector memory and Model Context Protocol (MCP) server for local semantic search and long-term memory.

Features

• MCP Integration: Fully compatible with the Model Context Protocol.
• Session-Scoped & Universal Memory: Scoped tools isolate memory per sessionId; universal tools provide shared, session-independent storage.
• Pluggable Architecture: Easily swap embedding providers and vector stores.
• Multiple Storage Backends: Supports Memory, Filesystem, and ChromaDB stores out of the box.
• Semantic Search: Use state-of-the-art embeddings for intelligent memory retrieval.
• DTS Indexing: Optimized search using Distance to Samples (DTS) logic.

Quick Start (using npx)

You can run the consciousness MCP server directly without installation using npx:

npx @one710/consciousness

By default, this will start an MCP server named "consciousness" using a FilesystemVectorStore (persisted to ./memory_store.json) and HFEmbeddingProvider.

Installation

npm install @one710/consciousness

Usage in Code

Creating an MCP Server

import { createServer } from "@one710/consciousness";
import { MemoryVectorStore } from "@one710/consciousness/vector/memory";
import { HFEmbeddingProvider } from "@one710/consciousness/embeddings/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);

Embedding Providers

Hugging Face (Local)

Uses @huggingface/transformers to generate embeddings locally on your CPU/GPU.

import { HFEmbeddingProvider } from "@one710/consciousness/embeddings/huggingface";
const provider = new HFEmbeddingProvider();

AI SDK (Cloud/Remote)

Uses the Vercel AI SDK to connect to any supported provider (e.g., OpenAI, Anthropic, Google).

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

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

Vector Stores

Memory Store (In-memory)

import { MemoryVectorStore } from "@one710/consciousness/vector/memory";
const store = new MemoryVectorStore(provider);

Filesystem Store (Local Persistence)

import { FilesystemVectorStore } from "@one710/consciousness/vector/filesystem";
const store = new FilesystemVectorStore(provider, "./memory-data.json");

Chroma Store (Distributed/Managed)

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

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

Working with Sessions

All store operations require a sessionId to isolate memories:

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 Tools

The MCP server exposes two sets of tools:

Scoped Tools (require sessionId)

| Tool | Description | | ---------------------- | --------------------------------------------------------------- | | add_to_scoped_memory | Store content scoped to a session | | search_scoped_memory | Semantic search within a session (cosine, euclidean, dts) | | forget_scoped_memory | Remove a specific memory by ID within a session | | clear_scoped_memory | Clear all memories for a session |

Universal Tools (no sessionId needed)

| Tool | Description | | ------------------------- | ---------------------------------------------------------------------- | | add_to_universal_memory | Store content in shared, session-independent memory | | search_universal_memory | Semantic search across universal memory (cosine, euclidean, dts) | | forget_universal_memory | Remove a specific memory by ID from universal memory | | clear_universal_memory | Clear all universal memories |

License

This project is licensed under the MIT License.