semantica
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@semantica Remember that the production database is read-only after 5 PM."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Semantica agent 接入入门
这是一个可以直接运行的 Semantica 小项目,专门回答一件事:
agent 是怎么接到 Semantica 上的?
结论先说清楚:
Semantica 不是 agent 框架。
它不调度工具、不跑 ReAct、不管理 multi-agent 对话。
它是 agent 下面的语义层:记忆、知识图谱、决策审计。
任何 agent(自己写的循环、Agno、LangChain、CrewAI、Claude、Cursor)都通过同一组插头接入。
你的 agent(自己写 / Agno / LangChain / CrewAI / Claude)
│
├── memory AgentContext.store / list
├── knowledge ContextGraph.add_node / query
├── decisions record_decision / 因果链
└── tools 框架 Toolkit 或 MCP
▼
Semantica五课默认不需要 LLM。第 2 课的决策可以额外接本地 runtime 或云端 API key,两者走同一条 OpenAI 兼容插头。
0. 环境
Python 3.11+
Intel macOS 会自动钉住仍提供 x86_64 轮子的 torch / onnxruntime / numba。其它平台由 Semantica 自己解析依赖。
Related MCP server: Spomory
1. 安装
git clone https://github.com/sin3000x/semantica-agent-starter.git
cd semantica-agent-starter
uv sync验证:
uv run python --version
uv run python -c "import semantica; print(semantica.__version__)"
uv run python main.py doctor第一次创建 VectorStore 可能下载 embedding 模型;第一次导入 Semantica 也会比较慢。
2. 开始上课
uv run python main.py
uv run python main.py 1课 | 做什么 |
1 | 插头就是 |
2 | 采购 agent:感知 → 查先例 → 决策 → 落盘 |
3 | 两个 agent 不发消息,读写同一张 |
4 | Agno / LangChain / CrewAI 只是把四个插座包成框架对象 |
5 | Claude / Cursor 走 MCP: |
uv run python main.py all3. 可选:接 LLM(runtime 或 API key)
第 2 课默认用规则:延期天数 > 库存天数 就升级。规则一直可测、可回退。
配置了 LLM 之后,decide() 会先问模型;解析失败或连不上就退回规则。Semantica 仍然只负责记住决定。
复制环境文件:
cp .env.example .env本地 runtime(无 key)
OpenCode 是一等 runtime:默认调用本机 opencode run,用你已经 opencode auth login 过的模型,不必再配一份 API key。
# 先装 OpenCode,并完成登录
# curl -fsSL https://opencode.ai/install | bash
# opencode auth login
SEMANTICA_LLM=opencode
# 可省略,缺省用 OpenCode 当前默认模型
# SEMANTICA_LLM_MODEL=anthropic/claude-sonnet-4-5已经 opencode serve 时,让 CLI 挂到现有服务上,避免每次冷启动:
SEMANTICA_LLM=opencode
OPENCODE_ATTACH=http://127.0.0.1:4096若你跑的是 OpenCode 的 OpenAI 兼容代理(例如 opencode-llm-proxy 的 :4010),把地址写成 /v1 即可:
SEMANTICA_LLM=opencode
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:4010/v1也适合 Ollama、vLLM、LM Studio,以及任何 OpenAI 兼容服务。
# Ollama
ollama pull llama3.1
# .env
SEMANTICA_LLM=ollama
SEMANTICA_LLM_MODEL=llama3.1
OLLAMA_HOST=http://127.0.0.1:11434# LM Studio / vLLM
SEMANTICA_LLM=compat
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:1234/v1
SEMANTICA_LLM_MODEL=local-model
SEMANTICA_LLM_API_KEY=local云端 API + key
默认推荐 SpaceXAI / xAI(OpenAI 兼容,XAI_API_KEY)。
XAI_API_KEY=xai-...
# 可省略 SEMANTICA_LLM,有 XAI_API_KEY 就会自动选 xai
SEMANTICA_LLM_MODEL=grok-4.6也可以用 OPENAI_API_KEY 或 GROQ_API_KEY。探测顺序:显式 SEMANTICA_LLM → XAI_API_KEY → OPENAI_API_KEY → GROQ_API_KEY。
uv run python main.py doctor
uv run python main.py 2不要把 .env 提交进 git。
4. MCP
配置样例在 mcp/。把 /ABS/PATH/TO/semantica-agent-starter 换成你的克隆路径。
uv run python -m semantica.mcp_server5. 测试
uv run pytesttests/test_llm.py 不访问网络。课程测试第一次大约需要几分钟(Semantica 导入和 VectorStore 初始化比较重)。
测试检查的是接入约束:
agent 写入的记忆和决定都能读回来
规则 agent 的第二次决定能追溯到第一次
两个 agent 共享同一张图
没配 key 时不会误接 LLM;配了坏响应会回退规则
6. 官方框架怎么接
框架 | 接到哪 |
自己写循环 | 直接调 |
Agno |
|
LangChain |
|
CrewAI |
|
Claude / Cursor | MCP |
本项目不安装这些 extra。第四课用一个小适配器把同样的四个插座跑通。
License
MIT
Available Tools
12 toolsadd_entityB
Add a node/entity to the Semantica knowledge graph.
Inputs: id (required), type, label, metadata.
add_relationshipB
Add a directed relationship (edge) between two entities in the knowledge graph.
Inputs: source (required), target (required), type, metadata.
export_graphA
Export the current knowledge graph. Formats: turtle, ttl, nt, xml, json-ld, json.
Inputs: format.
extract_entitiesB
Extract named entities (people, places, organisations, concepts) from text using Semantica NER.
Inputs: text (required).
extract_relationsA
Extract relations and (subject, predicate, object) triplets from text.
Inputs: text (required).
find_precedentsB
Find past decisions similar to a given scenario using hybrid similarity search.
Inputs: scenario (required), max_results.
get_causal_chainC
Trace the causal chain upstream or downstream from a decision.
Inputs: decision_id (required), direction, max_depth.
get_graph_analyticsA
Compute PageRank centrality and community detection over the knowledge graph.
Inputs: no named parameters.
get_graph_summaryA
Return a high-level summary of the current knowledge graph: node count, decision count, status.
Inputs: no named parameters.
query_decisionsB
Query recorded decisions by natural language, category, or get all recent decisions.
Inputs: limit, query, category.
record_decisionC
Record a decision into the Semantica knowledge graph with full context, causal links, and metadata.
Inputs: outcome (required), category (required), scenario (required), reasoning (required), +4 more.
run_reasoningA
Run forward-chaining IF/THEN rules over a set of facts to derive new facts.
Inputs: facts (required), rules (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a clearly distinct operation: extraction, knowledge graph mutation, decision querying, reasoning, analytics, and export. There is no meaningful overlap or ambiguity between the tool purposes.
All tool names follow a consistent snake_case verb_noun pattern, such as extract_entities, record_decision, query_decisions, and get_graph_analytics. The naming is predictable and easy to navigate.
Twelve tools is well-scoped for a knowledge graph and semantic reasoning server. Each tool covers a distinct capability without unnecessary bloat.
The tool set covers creation, querying, reasoning, analytics, and export, but lacks update/delete operations for entities, relationships, or decisions. This is a notable lifecycle gap that agents may need to work around.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared MCP memory for AI agents: knowledge base, skills, todos and agent-to-agent handoffs.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access hybrid vector, reasoning-based tree retrieval, and agent memory through the Model Context Protocol (MCP), supporting Claude Desktop and other MCP-compatible clients.76 npmApache 2.0
- AlicenseAqualityBmaintenanceEnables personal AI memory management through MCP tools for adding, searching, exporting, and deleting memories, with knowledge-graph retrieval and multi-hop association for clients like Claude Desktop and Cursor.61Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes a shared graph-based context engine as MCP tools for Claude, Copilot, and other AI agents, enabling knowledge ingestion, recall, search, and LLM-ready context assembly across sessions.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to govern and access memory engines over MCP, with scoped read/write permissions, journaling, secret scrubbing, and bounded context delivery at session start.MIT