projectmemory

README

ProjectMemory

ProjectMemory is an MCP (Model Context Protocol) server that provides persistent storage for conversation context information using SQLite. This allows LLMs to remember and retrieve relevant information from past interactions.

Overview

ProjectMemory implements two MCP tools:

1. save_context - Saves context (conversation snippets, inputs, outputs) to a persistent store
2. retrieve_context - Retrieves relevant context based on semantic search

The service handles:

• Summarizing text to extract key information
• Creating embeddings for semantic search
• Storing context with metadata in SQLite
• Searching for relevant context using vector similarity

Components

• Vector Package: Utilities for embedding operations and vector similarity
• Summarizer Package: Text summarization capabilities
• ContextStore Package: SQLite-based persistent storage
• Server Package: MCP server implementation
• Logger Package: Structured logging system

Getting Started

Prerequisites

• Go 1.20+
• SQLite

Configuration

Create a .projectmemoryconfig file in the project root:

{
  "store": {
    "sqlite_path": ".projectmemory.db"
  },
  "summarizer": {
    "provider": "basic"
  },
  "embedder": {
    "provider": "mock",
    "dimensions": 768
  },
  "logging": {
    "level": "info",
    "format": "text"
  }
}

You can also use environment variables to override configuration values:

# Set the database path
export SQLITE_PATH=".custom-db.db"

# Set log level
export LOG_LEVEL="debug"

For a detailed explanation of all configuration options, see the Configuration Reference.

Running the Server

From the project root:

go run cmd/project-memory/main.go

Using as a Library

ProjectMemory can be used as a library in your Go applications in multiple ways:

1. Direct Component Usage - Directly use the core components for maximum control
2. Helper Functions - Use the CreateComponents helper for easier initialization
3. High-Level API - Use the Server API for simplified operations

These approaches allow you to integrate ProjectMemory with your existing MCP server without conflicts. For detailed instructions and examples, see our Library Usage Guide and our comprehensive Embedding Guide.

Custom Logging

When embedding ProjectMemory in your application, you can override the default logger:

import (
    "github.com/localrivet/gomcp/logx"
    "github.com/localrivet/projectmemory"
)

func main() {
    // Create your custom logger
    logger := logx.NewLogger("debug")

    // Initialize the server with your custom logger
    server, err := projectmemory.NewServer(".projectmemoryconfig", logger)
    if err != nil {
        logger.Error("Failed to create server: %v", err)
    }

    // Alternatively, you can create a server first and then set the logger
    // server, err := projectmemory.NewServer(".projectmemoryconfig", nil)
    // if err != nil {
    //     // Handle error
    // }
    //
    // server.WithLogger(logger)

    // Now all ProjectMemory logs will be routed through your logger
    // Continue with your application...
}

Quick Example

import (
    "time"

    "github.com/localrivet/projectmemory"
    "github.com/localrivet/projectmemory/internal/contextstore"
    "github.com/localrivet/projectmemory/internal/summarizer"
    "github.com/localrivet/projectmemory/internal/vector"
)

// Option 1: Use the components directly
store := contextstore.NewSQLiteContextStore()
store.Initialize(".projectmemory.db")
defer store.Close()

summ := summarizer.NewBasicSummarizer(summarizer.DefaultMaxSummaryLength)
summ.Initialize()

emb := vector.NewMockEmbedder(vector.DefaultEmbeddingDimensions)
emb.Initialize()

// Now you can use these components directly in your code
// For example, to store context:
testText := "This is a test context to save."
summary, _ := summ.Summarize(testText)
embedding, _ := emb.CreateEmbedding(summary)
embeddingBytes, _ := vector.Float32SliceToBytes(embedding)
id := projectmemory.GenerateHash(summary, time.Now().UnixNano())
store.Store(id, summary, embeddingBytes, time.Now())

// Option 2: Use the high-level API with configuration
cfg := projectmemory.DefaultConfig()
cfg.Store.SQLitePath = ".custom-memory.db"
pmServer, err := projectmemory.NewServer(".projectmemoryconfig", nil)
if err != nil {
    // Handle error
}

// Save context using the high-level API
id, err = pmServer.SaveContext("This is a test context from the high-level API")
if err != nil {
    // Handle error
}

For a complete example of integrating with an existing MCP server, see examples/embed-in-mcp/main.go.

API Reference

Tool: save_context

Request:

{
  "context_text": "The text to save in the context store"
}

Response:

{
  "status": "success",
  "id": "generated-unique-id"
}

Tool: retrieve_context

Request:

{
  "query": "The query to search for",
  "limit": 5
}

Response:

{
  "status": "success",
  "results": ["Matching context entry 1", "Matching context entry 2", "..."]
}

Tool: delete_context

Request:

{
  "id": "context-entry-id-to-delete"
}

Response:

{
  "status": "success"
}

Tool: clear_all_context

Request:

{
  "confirmation": "confirm"
}

Response:

{
  "status": "success"
}

Tool: replace_context

Request:

{
  "id": "context-entry-id-to-replace",
  "context_text": "The new text to replace the existing context"
}

Response:

{
  "status": "success"
}

Documentation

• Installation Guide
• Configuration Reference
• API Reference
• Development Guide
• Architecture Documentation
• Library Usage Guide
• Embedding Guide - Comprehensive guide for embedding in your application

License

MIT License

Documentation

Index

• func CreateComponents(cfg *Config, logger *slog.Logger) (contextstore.ContextStore, summarizer.Summarizer, vector.Embedder, error)
• func GenerateHash(summary string, timestamp int64) string
• func SaveConfig(config *Config, path string) ([]byte, error)
• type Config
  • func DefaultConfig() *Config
• type Server
  • func NewServer(opts ServerOptions) (*Server, error)
  • func (s *Server) GetEmbedder() vector.Embedder
  • func (s *Server) GetStore() contextstore.ContextStore
  • func (s *Server) GetSummarizer() summarizer.Summarizer
  • func (s *Server) RetrieveContext(query string, limit int) ([]string, error)
  • func (s *Server) SaveContext(text string) (string, error)
  • func (s *Server) Start() error
  • func (s *Server) Stop() error
• type ServerOptions

Functions

func CreateComponents

func CreateComponents(cfg *Config, logger *slog.Logger) (contextstore.ContextStore, summarizer.Summarizer, vector.Embedder, error)

CreateComponents creates and initializes the components of the ProjectMemory service without creating a server instance. This is useful for components that need direct access to the store, summarizer, and embedder.

func GenerateHash

func GenerateHash(summary string, timestamp int64) string

GenerateHash creates a hash from the summary and a timestamp This is a convenience wrapper around the internal util.GenerateHash function

func SaveConfig

func SaveConfig(config *Config, path string) ([]byte, error)

SaveConfig saves the configuration to a file and returns the JSON content.

Types

type Config

type Config = config.Config

Config represents the configuration for the ProjectMemory service.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns the default configuration for the ProjectMemory service.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server represents the ProjectMemory service.

func NewServer

func NewServer(opts ServerOptions) (*Server, error)

NewServer creates a new ProjectMemory Server with the given options. If opts.Config is provided, it will be used directly. Otherwise, if opts.ConfigPath is provided, configuration will be loaded from that path. If neither is provided, DefaultConfig() will be used. If opts.Logger is nil, slog.Default() will be used.

func (*Server) GetEmbedder

func (s *Server) GetEmbedder() vector.Embedder

GetEmbedder returns the embedder instance used by the server.

func (*Server) GetStore

func (s *Server) GetStore() contextstore.ContextStore

GetStore returns the context store instance used by the server.

func (*Server) GetSummarizer

func (s *Server) GetSummarizer() summarizer.Summarizer

GetSummarizer returns the summarizer instance used by the server.

func (*Server) RetrieveContext

func (s *Server) RetrieveContext(query string, limit int) ([]string, error)

RetrieveContext retrieves context entries similar to the given query.

func (*Server) SaveContext

func (s *Server) SaveContext(text string) (string, error)

SaveContext saves the given text to the context store.

func (*Server) Start

func (s *Server) Start() error

Start starts the ProjectMemory service.

func (*Server) Stop

func (s *Server) Stop() error

Stop stops the ProjectMemory service.

type ServerOptions

type ServerOptions struct {
	Config     *Config      // Pre-filled config. If nil, ConfigPath is used.
	ConfigPath string       // Path to config file. Used if Config is nil. If both are empty, DefaultConfig() is used.
	Logger     *slog.Logger // External logger. If nil, slog.Default() is used.
}

ServerOptions defines the options for creating a new Server.