Persistent knowledge graph + vector memory for AI agents
Website · API Docs · Changelog

Durable, searchable, graph-structured memory across sessions. Designed for AI agents and the developers who build them.

• Go + Gin — Fast, type-safe REST API
• PostgreSQL 16+ + pgvector — Knowledge graph storage with vector similarity search
• Hybrid search — Reciprocal Rank Fusion combines full-text + vector results; falls back to text-only if embeddings are unavailable
• Salience scoring — Every node tracks access patterns, recency, and user boosts to surface the most relevant memories automatically
• AES-256-GCM encryption — All node/edge properties encrypted at rest, transparent to API consumers
• Ollama embeddings — Automatic vector generation (qwen3-embedding:0.6b)
• Row-Level Security — Complete tenant isolation; one API key = one tenant
• WebSocket — Real-time change notifications via PostgreSQL LISTEN/NOTIFY

The persistor CLI is a first-class interface for interacting with your knowledge graph without writing a single HTTP request.

# Install
make build-cli && sudo make install-cli   # installs to /usr/local/bin/persistor

# Configure (stored in ~/.persistor/config.yaml)
persistor init

Key commands:

# Nodes
persistor node create --type person --label "Alice Smith" --id alice
persistor node get alice
persistor node list --type person --min-salience 0.5

# Search
persistor search "active projects"           # full-text
persistor search --semantic "project risks"  # vector similarity
persistor search --hybrid "database memory"  # text + vector (recommended)

# Graph traversal
persistor graph neighbors alice
persistor graph traverse alice --hops 3
persistor graph context alice              # node + neighbors + edges in one call

# Salience
persistor salience boost alice             # mark a node as important
persistor salience recalc                  # recompute scores from access patterns

# Admin & diagnostics
persistor admin stats                      # knowledge graph statistics
persistor doctor                           # check server connectivity and config

Global flags: --url (default http://localhost:3030, or PERSISTOR_URL), --api-key (or PERSISTOR_API_KEY), --format json|table|quiet.

Every node and edge carries a salience_score that Persistor updates automatically:

• Access patterns — nodes read frequently score higher
• Recency — recently accessed nodes decay more slowly
• User boosts — explicit salience/boost marks a node as important (user_boosted: true)
• Supersession — outdated nodes link to their replacement via superseded_by
• Recalc — POST /salience/recalc (or persistor salience recalc) refreshes all scores

Query by minimum salience (?min_salience=0.5) to retrieve only what matters right now.

• Go 1.25+
• PostgreSQL 16+ with pgvector extension
• Ollama running locally (for embedding generation)

git clone https://github.com/persistorai/persistor.git
cd persistor

# Configure environment (or use systemd EnvironmentFile — see Deployment)
export DATABASE_URL="postgres://persistor:<password>@localhost:5432/persistor?sslmode=disable"
export ENCRYPTION_PROVIDER=static
export ENCRYPTION_KEY="<64-hex-char-key>"  # 32 bytes, hex-encoded
export PORT=3030

# Build and run (migrations run automatically on startup)
make build
make run

curl http://localhost:3030/api/v1/health
# {"status": "ok"}

curl http://localhost:3030/api/v1/ready
# {"status":"ok","checks":{"database":"ok","schema":"ok","ollama":"ok"}}

See INTEGRATION.md for the complete API reference with curl examples, data model documentation, and agent-specific usage patterns.

All under /api/v1/ unless noted.

make build          # Build server and CLI binaries
make run            # Build and run the server
make test           # Run tests with race detection
make test-coverage  # Tests + HTML coverage report
make lint           # golangci-lint
make lint-fix       # Auto-fix lint issues
make format         # gofmt + goimports
make ci             # Full CI: format → vet → lint → test + coverage

Persistor ships as a Go binary + systemd service. Docker is intentionally not supported — the binary is small, fast, and runs directly on the host alongside PostgreSQL and Ollama.

# /etc/systemd/system/persistor.service
[Unit]
Description=Persistor
After=postgresql.service ollama.service
Requires=postgresql.service

[Service]
Type=simple
User=persistor
ExecStart=/usr/local/bin/persistor-server
EnvironmentFile=/etc/persistor.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Place environment variables in /etc/persistor.env (chmod 600, owned by root).

export ENCRYPTION_PROVIDER=vault
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=<your-vault-token>

The service fetches the encryption key from Vault at startup, avoiding plaintext keys in environment files.

./scripts/backup.sh              # pg_dump + verify + encrypt + rotate
./scripts/restore.sh <file>      # Restore from encrypted backup
./scripts/health-check.sh        # Quick health check

AGPL-3.0. See LICENSE for details. Commercial licensing is available for organizations that cannot use AGPL — contact [email protected].

The Go SDK (client/) is Apache-2.0 to allow unrestricted client integration.

See CHANGELOG.md for release history.